38.5 Time of Day

This section explains how to determine the current time and time zone.

Most of these functions represent time as a list of four integers (sec-high sec-low microsec picosec). This represents the number of seconds from the epoch (January 1, 1970 at 00:00 UTC), using the formula: high * 2**16 + low + micro * 10**−6 + pico * 10**−12. The return value of current-time represents time using this form, as do the timestamps in the return values of other functions such as file-attributes (see Definition of file-attributes). In some cases, functions may return two- or three-element lists, with omitted microsec and picosec components defaulting to zero.

Function arguments, e.g., the time argument to current-time-string, accept a more-general time value format, which can be a list of integers as above, or a single number for seconds since the epoch, or nil for the current time. You can convert a time value into a human-readable string using current-time-string and format-time-string, into a list of integers using seconds-to-time, and into other forms using decode-time and float-time. These functions are described in the following sections.

Function: current-time-string &optional time zone

This function returns the current time and date as a human-readable string. The format does not vary for the initial part of the string, which contains the day of week, month, day of month, and time of day in that order: the number of characters used for these fields is always the same, so you can reliably use substring to extract them. You should count characters from the beginning of the string rather than from the end, as the year might not have exactly four digits, and additional information may some day be added at the end.

The argument time, if given, specifies a time to format, instead of the current time. The optional argument zone defaults to the current time zone rule. See Time Zone Rules.

(current-time-string)
     ⇒ "Wed Oct 14 22:21:05 1987"

Function: current-time

This function returns the current time, represented as a list of four integers (sec-high sec-low microsec picosec). These integers have trailing zeros on systems that return time with lower resolutions. On all current machines picosec is a multiple of 1000, but this may change as higher-resolution clocks become available.

Function: float-time &optional time

This function returns the current time as a floating-point number of seconds since the epoch. The optional argument time, if given, specifies a time to convert instead of the current time.

Warning: Since the result is floating point, it may not be exact. Do not use this function if precise time stamps are required.

time-to-seconds is an alias for this function.

Function: seconds-to-time time

This function converts a time value to list-of-integer form. For example, if time is a number, (time-to-seconds (seconds-to-time time)) equals the number unless overflow or rounding errors occur.